MacFormat 1995 March/macformat-022.iso/Shareware City/Developers/HoW Developer’s Kit 1.2/HoWSample/HoWSample Help/HoWSample Help.rsrc/STR#_1029.txt

Text File | 1994-10-17 | 9.0 KB | 365 lines






@


@





åClient-Server Relations





This section explains how a client conducts its relations with the help

server, with the help of the HoWLib client interface library.










xThe Client Engine



The interface, described in the next subsection, consists of two utility

functions, HoWFindHelpFile and HoWOpen, and three client engine

functions, HoWRegister, HoWDisplay, and HoWDeregister.  Your

application will generally find its help file and register on entry, display

in response to menu, mouse, and key events, and deregister on exit.

Apart from that, the only requirement is to call AEProcessAppleEvent

when you receive any high-level event that isn’t known not to be an Apple

event, which is generally good practice.


(Click this hot button to hear what famous Apple product doesn’t play by


the rules.)





If your program is not an application, it cannot use client engine functions.

It can call HoWFindHelpFile to find its help file if it is separate, and it can

call HoWOpen to tell the server to open the help file (starting the server if

necessary).  It cannot communicate with the server using tags, neither

for display nor for Help events.



When you register, you have the option of starting the server

immediately, or deferring until the first display.  Unless the server’s

availability is critical to your application, you will usually choose the

latter, less obnoxious, option.



The client engine handles the rest of the relationship between client and

server.  Your application doesn’t have to care where the server is, or

whether it’s running already, or what to do if the user exits the server

while your application is running.  The client engine, contained in a

purgeable code segment named “HoWLib,” manages these details for you.

If the server is started by some other method while your application is

running, the engine senses this, and makes sure that the server adds your

application to its Help menu.  The engine also takes care of Help events by

invoking your handler, if you have one.



If you call HoWDisplay when the server is not started, and the server

can’t be found on any mounted volume, the engine posts an alert, offering

to save the help text as a TeachText document.  If the user agrees, the

engine creates the file and opens it automatically.  If the file would be too

large for TeachText to open, the engine breaks it into several files and

puts them in a new folder.








xCasual Displays



HoWSample is a very simple client application which demonstrates good

client practices.  Whenever the user selects the main Help menu item or

presses the Help key, it calls HoWDisplay with “tag” set to 0, or if a

dialog is open, some tag value appropriate to the cursor location.

Subsidiary items in the Help menu cause calls to HoWDisplay with other

tag values, demonstrating how a client can index the help file.





HoWSample also demonstrates how you can implement context-sensitive

help using casual displays.  The “casual” argument to the HoWDisplay

function is always false when HoWSample calls it in reaction to a direct

user action.  HoWSample requests a casual display whenever the user

selects a menu item or clicks on a dialog item.  Setting “casual” to true

makes the call more of a hint to the server, and less of an order.  This

mechanism allows the client to use the server’s optional “follow” mode,

effectively taking control of the help display.



Specifically, casual displays are different in the following ways:  First,

they do not start the server if it isn’t running.  Second, they do not bring

the server into the foreground.  Third, they are ineffective if the server

is not already displaying the client’s help file.  Fourth, they are

ineffective if the user has not selected the “follow” option in the

server’s Preferences dialog.








xHoWLib Client Interface Library Functions



This subsection describes exactly what the HoWLib functions do, and how

and when to call them, quoting from the C header file.  You may want to

follow along in the HoWSample source code as you read these function

descriptions.







/* The Help event handler receives an event ID which is the negative of

the tag associated with the clicked text. */

typedef pascal void (*HoWHandlerProcPtr) (short id);







/* Find the help file referenced by the 'alis' resource with ID "aliasResID"

in the resource file with reference number "preferencesFileRefNum", or

in the resource file with reference number "applicationFileRefNum" if the

resource does not exist in the preferences file or cannot be resolved.  The

alias record, possibly changed by UpdateAlias, is written back to the

preferences file if possible.  The application file is not changed.

Resolution is relative to the application file, so it can take advantage of

relative information in the alias resource if present.  If the help file

cannot be found by a fast search, one exhaustive search will be done on

the alias record in the application file.  A failed exhaustive search is noted

in the preferences file so that it is not repeated; this note remains until

the preferences file is deleted, or until a later fast search successfully

finds the help file.  If you do not maintain a separate preferences file, set

both resource file reference numbers to the same value, and the

application file will be treated as though it were also the preferences file.

*/

pascal OSErr HoWFindHelpFile (short preferencesFileRefNum,

                              short applicationFileRefNum,

                              short aliasResID, FSSpecPtr helpFile);







/* Register or re-register with the help server.  The help file may be any

file, including the main application file.  If the help file has a 'vers'(1)

resource, and the version (first word) does not match "version",

wrongVersionErr is returned.  If there is no master resource in the help

file for the current script's current language, nor for "defaultLanguage",

nor for langEnglish, noMasterResErr is returned.  The server will prefer

to use its own language over "defaultLanguage".  By re-registering, the

client can switch to another help file.  If the server is not already

started, and "startServer" is true, HoWRegister will try to start the

server, which may result in many OS error codes, as well as

noServerApplErr, a non-fatal code returned for your information (see

HoWDisplay below).  If the server is not already started, and

"startServer" is false (which it should be for most clients), the usual

return code is noErr, meaning that the actual registration has been

deferred until the first non-casual display (see below) or until the server

starts by some other method.  Gestalt checks may result in other error

codes listed above; the expected error code under System 6 is

noAppleEventsErr.  The Help event handler is optional; pass nil if the

client does not support them. */

pascal OSErr HoWRegister (const FSSpec *helpFile, short version,

                          LangCode defaultLanguage, Boolean startServer,

                          HoWHandlerProcPtr handler);







/* Display the help file at the indicated tag position.  If "tag" is zero, the

last seen position is retained.  If the server is not already started, and

"casual" is false, this will attempt to start the server; if the server is

absent, the user sees an alert offering to save a readable copy using

TeachText and open it for viewing, unless the client is background-only,

in which case no alerts appear, and the document is created on the

desktop.  A casual display is effective only if the server is started and

running in the background, with the "follow" option in effect, and already

displaying this client's help file.  A casual display always leaves the client

in the foreground; a non-casual display always brings the server to the

foreground.  Note that modal dialogs will prevent the server from coming

to the foreground unless they are hidden before this call. */

pascal OSErr HoWDisplay (short tag, Boolean casual);







/* Deregister with the help server.  If the client fails to deregister

before it exits, the server will deregister it automatically. */

pascal OSErr HoWDeregister (void);







/* Launch the help server, if necessary, to open and display the given

help file.  This method is suggested for use by programs which are not

applications; applications should use HoWRegister instead (see above).  If

the server is absent, a TeachText copy is created on the desktop and

opened (as for a background-only application calling HoWDisplay).  Version

checking is not performed, and the current script's current language is

always used.  This may be called by 'INIT' logic in control panels or

extensions, because it uses the Notification Manager; allow 5000 bytes

when calculating the system heap requirement for your 'sysz' resource.

*/

pascal OSErr HoWOpen (const FSSpec *helpFile);